File Operations IPC
This document provides comprehensive documentation for file operation IPC handlers focused on importing and reading email lists. It covers the ‘import-email-list’ dialog handler and the ‘read-email-list-file’ parser, including dialog configuration, supported file formats, parsing logic, path resolution, error handling, return value schemas, and security considerations. It also includes practical examples for batch processing, duplicate removal, and format conversion.
The file operation IPC handlers are implemented in the Electron main process and exposed to the renderer via a secure preload bridge. The frontend component demonstrates usage of these handlers to import and parse email lists.
BulkMailer.jsx"] --> Preload["Preload Bridge
preload.js"] Preload --> Main["Main Process Handlers
main.js"] Main --> FS["File System
fs module"] Main --> CSV["CSV Parser
csv-parser"] Main --> Dialog["Dialog API
electron.dialog"] FE --> |invoke 'import-email-list'| Preload FE --> |invoke 'read-email-list-file'| Preload FE --> |progress events| FE
Diagram sources
Section sources
IPC handler ‘import-email-list’: Opens a native file open dialog configured to accept text and CSV files, returning a structured result object containing the selected file paths and cancellation status.
IPC handler ‘read-email-list-file’: Reads the content of a given file path, parses CSV files using flexible column detection, and processes text files by extracting lines containing ‘@’. Returns a newline-delimited string of validated email addresses.
Key responsibilities:
Dialog configuration and file filter options
Path resolution and file type detection
CSV parsing with flexible column detection
Text file processing and email validation
Error propagation and handling
Section sources
The file operation IPC flow connects the frontend UI to the Electron main process, which interacts with the file system and parsers.
Diagram sources
IPC Handler: import-email-list#
Purpose:
Presents a native file open dialog to select an email list file.
Filters accepted file types to text and CSV files plus all files.
Dialog configuration:
Properties: openFile
Filters:
Text Files: txt
CSV Files: csv
All Files: * (fallback)
Return value schema:
canceled: boolean indicating whether the dialog was canceled
filePaths: array of selected file paths (only the first path is used in the frontend)
Usage in frontend:
Invoked via window.electronAPI.importEmailList()
On success, the first filePath is passed to read-email-list-file
Notes:
The handler returns the raw dialog result, allowing the renderer to decide how to process the file.
Section sources
IPC Handler: read-email-list-file#
Purpose:
Reads and parses the content of a selected email list file.
Supports CSV and text formats with flexible email detection.
Processing logic:
CSV parsing:
Uses streaming to avoid memory pressure on large files.
Detects email columns by common names (email, Email, EMAIL, address, Address, ADDRESS) or falls back to the first column.
Validates entries by presence of ‘@’.
Joins extracted emails with newline separators.
Text file processing:
Splits content by newline.
Trims whitespace and filters lines containing ‘@’.
Return value schema:
String containing newline-delimited email addresses.
Throws errors on file access failures or parsing errors.
Error handling:
Catches and rethrows errors from file system operations and CSV parsing.
Frontend displays error messages and prevents silent failures.
Path resolution:
Relies on the filePath provided by the caller (import-email-list result).
No additional path normalization is performed in the handler.
Section sources
Frontend Integration#
The frontend component invokes import-email-list, checks for cancellation, extracts the first file path, and calls read-email-list-file.
Displays the count of imported email addresses and handles errors gracefully.
Validation and processing:
The frontend performs additional email format validation using a regex before sending emails.
This complements the handler’s basic ‘@’ check.
Section sources
Supporting Utilities#
Development environment detection is available for logging and conditional behavior.
The project README documents security features including context isolation and secure IPC.
Section sources
The file operation handlers depend on:
Electron dialog API for file selection
Node.js fs module for file reading
csv-parser for streaming CSV parsing
Frontend preload bridge for secure IPC invocation
Diagram sources
Section sources
Streaming CSV parsing: The handler streams CSV data to avoid loading entire files into memory, improving performance for large datasets.
Text file processing: Simple line-by-line processing with minimal allocations.
Frontend validation: Regex-based validation occurs after parsing to reduce unnecessary network calls.
Recommendations:
Prefer CSV format for structured data to leverage flexible column detection.
For very large files, consider chunked processing and progress reporting.
Ensure adequate delay between operations to avoid overwhelming the system.
[No sources needed since this section provides general guidance]
Common issues and resolutions:
Dialog canceled or no file selected:
The handler returns canceled true and empty filePaths. The frontend should check these values before proceeding.
Unsupported file type:
The handler does not explicitly reject unsupported extensions; ensure the dialog filters are respected.
File access failures:
Errors are thrown and surfaced to the frontend. Verify file permissions and path correctness.
Parsing errors:
CSV parsing errors are caught and rethrown. Validate CSV headers or switch to text format with ‘@’ separated entries.
Security considerations:
Context isolation and secure IPC are enabled, preventing direct Node.js access from the renderer.
Input sanitization is handled by the frontend email regex validation prior to sending emails.
Rate limiting is implemented in email handlers to prevent abuse.
Section sources
The file operation IPC handlers provide a robust foundation for importing and parsing email lists. The ‘import-email-list’ dialog offers configurable filters, while ‘read-email-list-file’ delivers flexible CSV parsing and text processing with clear return schemas. Combined with frontend validation and secure IPC, these handlers support reliable batch email list processing workflows.